//+------------------------------------------------------------------+
//|                        FileBMP.mqh BMP文件操作类头文件           |
//|                版权所有 2000-2025, MetaQuotes Ltd.              |
//|                        官方网址: https://www.mql5.com            |
//+------------------------------------------------------------------+
#include <Object.h>

//+------------------------------------------------------------------+
//| BMP文件头结构定义                                                |
//+------------------------------------------------------------------+
/**
 * @brief BMP文件头结构（存储文件格式和基本信息）
 */
struct BITMAPFILEHEADER
  {
   ushort            bfType;         // 文件类型标识（必须为BM，即0x4D42）
   uint              bfSize;         // 整个文件的大小（字节）
   ushort            bfReserved1;    // 保留字段1（必须为0）
   ushort            bfReserved2;    // 保留字段2（必须为0）
   uint              bfOffBits;      // 像素数据相对于文件开头的偏移量（字节）
  };

/**
 * @brief BMP信息头结构（存储图像的详细参数）
 */
struct BITMAPINFOHEADER
  {
   uint              biSize;         // 本结构的大小（字节，固定为40）
   int               biWidth;        // 图像宽度（像素）
   int               biHeight;       // 图像高度（像素，正数表示数据从下到上存储）
   ushort            biPlanes;       // 色彩平面数（必须为1）
   ushort            biBitCount;     // 每个像素的位数（本类仅支持32位）
   uint              biCompression;  // 压缩方式（本类仅支持无压缩）
   uint              biSizeImage;    // 像素数据大小（字节）
   int               biXPelsPerMeter;// 水平分辨率（像素/米）
   int               biYPelsPerMeter;// 垂直分辨率（像素/米）
   uint              biClrUsed;      // 使用的颜色数（0表示使用所有颜色）
   uint              biClrImportant; // 重要颜色数（0表示所有颜色都重要）
  };

// BMP文件类型标识（"BM"的十六进制表示）
#define BM 0x4D42

//+------------------------------------------------------------------+
//| CFileBMP类                                                       |
//| 功能：BMP图像文件专用操作类，支持32位无压缩BMP文件的读写         |
//| 继承：public CObject（基于MT5核心对象类扩展）                     |
//+------------------------------------------------------------------+
class CFileBMP : public CObject
  {
protected:
   int               m_handle;             // BMP文件句柄（INVALID_HANDLE表示未打开）
   BITMAPFILEHEADER  m_file_header;        // BMP文件头（存储文件格式信息）
   BITMAPINFOHEADER  m_info_header;        // BMP信息头（存储图像参数）

public:
   /**
    * @brief 构造函数：初始化BMP文件操作实例
    * @details 初始化句柄为无效值，清空文件头结构
    */
                     CFileBMP(void);

   /**
    * @brief 析构函数：销毁BMP文件操作实例
    * @details 自动关闭已打开的文件，释放资源
    */
                    ~CFileBMP(void);

   /**
    * @brief 以写入模式打开BMP文件（用于创建新BMP图像）
    * @param file_name [in] 文件名/路径（如 "image.bmp"）
    * @param common_flag [in] 是否使用公共文件夹：true-公共文件夹，false-终端私有文件夹
    * @return int - 操作结果：成功返回文件句柄（>0），失败返回INVALID_HANDLE（-1）
    * @note 打开模式为二进制写入，支持共享读写
    */
   int               OpenWrite(const string file_name,bool common_flag=false);

   /**
    * @brief 以读取模式打开BMP文件（用于读取现有BMP图像）
    * @param file_name [in] 文件名/路径
    * @param common_flag [in] 是否使用公共文件夹
    * @return int - 操作结果：成功返回文件句柄（>0），失败返回INVALID_HANDLE（-1）
    * @note 仅支持32位无压缩BMP文件，打开时会自动验证文件头合法性
    */
   int               OpenRead(const string file_name,bool common_flag=false);

   /**
    * @brief 将32位像素数组写入BMP文件（创建图像）
    * @param uint_array [in] 像素数据数组（每个元素为32位ARGB值，0xAARRGGBB格式）
    * @param width [in] 图像宽度（像素，必须为正数）
    * @param height [in] 图像高度（像素，必须为正数）
    * @return int - 操作结果：
    *         - 成功：返回写入的字节数（像素数据总大小）
    *         - 失败：-1（文件未打开），-2（数组大小不足）
    * @note 需先调用OpenWrite成功打开文件，数组大小需至少为width*height
    */
   int               Write32BitsArray(uint& uint_array[],const int width,const int height);

   /**
    * @brief 从BMP文件读取32位像素数组（解析图像）
    * @param uint_array [out] 接收像素数据的数组（需提前分配足够空间）
    * @param width [out] 输出图像宽度（像素）
    * @param height [out] 输出图像高度（像素）
    * @return int - 操作结果：
    *         - 成功：返回读取的字节数（像素数据总大小）
    *         - 失败：-1（文件未打开）
    * @note 需先调用OpenRead成功打开文件，数组大小需至少为width*height
    */
   int               Read32BitsArray(uint& uint_array[],int& width,int& height);

   /**
    * @brief 关闭当前打开的BMP文件
    * @note 释放文件句柄，重置内部状态；未打开文件时调用无操作
    */
   void              Close(void);
  };
//+------------------------------------------------------------------+
